fix(cli): let the dev artifact door own stack-declared security metadata on a host config - #14631

Fixes #14397

os dev over a HOST config composed two writers for stack-declared security metadata over one stack. This PR makes the artifact door the single registrar on that boot shape, the way createStandaloneStack already does for the artifact boot — triage's option 1, and only after the two readings triage made the dispatchable unit.

The two readings, first — this card's actual deliverable

Both were taken by booting the real os dev supervisor (packages/cli/bin/run.js dev, which compiles, writes OS_INTERNAL_ARTIFACT_PATH, and spawns os serve --dev), never a hand-composed kernel. Full transcript on #14397.

1. Does os dev compile a HOST config into dist/objectstack.json, and is the HMR door composed? Yes to both — the path is LIVE, not dead.

Case: examples/app-showcase, a host config by isHostConfig's own rule (its plugins[] holds new ConnectorOpenApiPlugin(), new ConnectorMcpPlugin(...), new ConnectorRestPlugin(...), new ConnectorSlackPlugin(...), plus the marketplace and runtime-config plugins) that declares all four ADR-0057 collections at top level. apps/objectos does not exist in this repo — serve.ts names it only in a comment — so the in-repo host config above is the live case. dist/ was deleted first:

  → Compiling objectstack.config.ts → dist/objectstack.json...
  Artifact: .../examples/app-showcase/dist/objectstack.json (696.0 KB)
INFO [MetadataPlugin] Loading metadata from local artifact file {"path":".../app-showcase/dist/objectstack.json"}
INFO [MetadataPlugin] Artifact metadata loaded {...,"totalRegistered":246}
[MetadataPlugin] artifact file watcher attached .../app-showcase/dist/objectstack.json
[MetadataPlugin] HMR endpoint registered at /api/v1/dev/metadata-events

dev.ts never asks what shape the config is: needsCompile is !flags.artifact && (flags.compile || !fs.existsSync(artifactPath)). It then hands the resolved path down unconditionally, and resolveDefaultArtifactPath returns an explicit path verbatim, so the door's guard resolves on every os dev boot.

The second writer is in the same boot, 620 ms after the door:

2026-09-02T10:20:21.215Z INFO [MetadataPlugin] Artifact metadata loaded {...,"totalRegistered":246}
2026-09-02T10:20:21.835Z INFO Registered stack-declared security metadata {"appId":"com.example.showcase","count":23}

2. Which copy wins? The wrap's on a cold boot — and the door's after the first reload. The winner changes mid-run.

The card's answer was an inference from kernel.use order ("positionally the door's copy would land last"). That inference is falsified for the cold boot. registerInMemory is a Map.set, so the last writer wins, and the wrap registers last.

Reading registry CONTENT needs an in-process observer, so this half was measured on a minimal host config built from the repo's own examples — same composition (instantiated plugin in plugins[], all four collections at top level, no AppPlugin and no MetadataPlugin of its own) plus one observer plugin that samples metadata.list(kind) on a timer and changes none of the three predicates under test. The compiled twin's label values were rewritten on disk so the two copies are distinguishable by value:

2026-09-02T10:28:15.232Z INFO [MetadataPlugin] Artifact metadata loaded {...,"totalRegistered":5}
2026-09-02T10:28:15.453Z INFO [MetadataPlugin] artifact auto-reloaded (file watcher) {"path":".../dist/objectstack.json"}

Four further samples over the next 45 s hold the door's copy. So the p2 note on the card is measured behaviour, not a worry: these collections have one shape from a cold boot and a different one after the first recompile, with no restart and no signal.

One correction to the card's description. The card says the module copy carries a sharing rule's condition as a bare string. On a CONFIG boot it does not: defineStack() defaults to strict: true and runs ObjectStackDefinitionSchema.safeParse itself, so schema defaults and the ADR-0122 input transform are already applied to the object the wrap registers. What the module copy still lacks is the door's ADR-0010 stamp, and — the part that matters — it is a SECOND copy free to diverge from the artifact for any reason, which the flip above demonstrates. The two-writer class is real; that one detail of its description belonged to the artifact boot's raw bytes.

The fix

serve.ts knows both facts in one function, so the decision is made once, next to the wrap:

• the dev artifact door is resolved and CONSTRUCTED before the wrap, into a single devArtifactDoor value;
• the wrap is built as new AppPlugin(config, undefined, devArtifactDoor ? { securityMetadataRegistrar: 'artifact-door' } : {});
• only the kernel.use stays at its original site, after the HonoServer composition, where MetadataPlugin's route-mounting ordering requirement lives.

Registrar for the four collections, by boot shape:

Why the door instance is constructed early rather than the boolean recomputed. One value has to decide both facts, or the two expressions can drift — and the drift is invisible, because a boot with no registrar looks exactly like a boot with one. Declaring the option with no door composed would be strictly worse than the divergence it removes: measured, os serve over the same host config has a metadata service and the wrap is its ONLY writer (Registered stack-declared security metadata {"appId":"com.probe.hostcfg","count":4}, no door in that boot), so the four collections would end up with no registrar at all — the silent hole #12892 measured on the artifact boot. hasMetadataPlugin is read one block earlier than before and the answer is identical: plugins is not mutated between the two points except by the AppPlugin append itself, and an AppPlugin is not a MetadataPlugin.

The door is gated on EXISTENCE, not resolution. resolveDefaultArtifactPath hands an explicitly named path back verbatim with no existence check, and the door tolerates a missing file at start() with an info line — so gating on resolution alone would let os dev --artifact ./typo.json over a host config boot green with NO registrar for the four kinds. The door is therefore composed only when fs.existsSync(hmrArtifactPath), with the gate before the construction, and the warning names the missing path:

  ⚠ Dev metadata-HMR endpoint not enabled: no compiled artifact at PATH
    Stack-declared security metadata stays with the app wrap, its registrar on every
    boot without a door.

The trade this makes is recorded in the code: on that boot the dev SSE endpoint is not mounted either, because the plugin that mounts it is the one not composed. Composing the door anyway and only withholding the registrar would keep that convenience by re-creating the two-writer divergence — the watcher picks the artifact up if it later appears and registers a second copy behind a wrap that already registered its own.

The kernel.use catch keeps its pre-existing one-line message. It is deliberately NOT the place to warn that the four collections went unregistered: Kernel.use only validates the plugin and registers it by name, and init / start run later in bootstrap, so for an already-constructed MetadataPlugin on a still-idle kernel that catch does not fire.

Fences honoured

createStandaloneStack and packages/metadata/** are untouched — this card is not #12892's, and that PR's fence holds. plugin-detection.ts (isHostConfig / shouldBootWithLibrary) was read, not tidied. Options 2 and 3 are closed by triage. PR #11336 untouched.

Verification

Head 0337430d4c. The PR carries one fix commit, three origin/main merges, and three patch-round commits answering the contract review.

Pin, red-first by ablation. packages/cli/src/commands/serve-host-config-security-registrar.pin.test.ts. The ablation restores the pre-gate serve.ts from 3dfd83a0e4 and runs the pin, then restores from HEAD and runs it again. Both legs proven on disk by blob hash, never by an editor's exit code, with a trap ... EXIT INT TERM restoring an absolute path:

HEAD blob: 86b5052c35fd148c43aa494f9f12ffd095fd9298
BASE blob: c85c46a26e12e8157a46c35f09457a456eed3d4b
on-disk blob after mutation: c85c46a26e12e8157a46c35f09457a456eed3d4b
  removed-text count (fs.existsSync(hmrArtifactPath)): 0
  restored-text count (The app wrap deferred):         1
ABLATED RUN EXIT=1
  × the door is composed only when its artifact EXISTS, not merely resolves
  × the `kernel.use` catch does not claim a consequence it cannot have
  Tests  2 failed | 4 passed (6)
on-disk blob after restore: 86b5052c35fd148c43aa494f9f12ffd095fd9298
git diff HEAD -- serve.ts: EMPTY (restore proven)
  restored-text count (fs.existsSync(hmrArtifactPath)): 1
RESTORED RUN EXIT=0
  Tests  6 passed (6)

Exactly the two assertions the patch round added go red against the pre-gate wiring; the four that predate it stay green. An earlier ablation attempt on a freshly re-created worktree was NOT MEASURED, not a red — with no built dependency closure the pin's @objectstack/runtime import failed to resolve and BOTH legs reported Test Files 1 failed (1) / no tests. The numbers above are from the tree after pnpm --filter '@objectstack/cli^...' build.

Targeted, under the shared verify lock (VERDICT command-exit 0): pnpm --filter @objectstack/cli typecheck EXIT=0; the pin EXIT=0, Test Files 1 passed (1) / Tests 6 passed (6). The package's tsconfig.json has include: ["src"] and no exclude, so that typecheck does cover the test file.

Whole-repo lint: pnpm lint (eslint . --no-inline-config) EXIT=0, 153 s. Not narrowed.

Gate union. At 3dfd83a0e4, dispatch-gates.mjs --repo objectstack-ai/objectstack --commands derived 38 families from the real change set (3 paths, three-dot against the merge base); all 38 were run with exit codes captured before any pipe and recorded byte-for-byte, and --ran reconciled: ✓ dispatch-gates --ran: 38 derived famil(ies) accounted for — 38 run, 0 NOT-MEASURED. Tally: 35 exit 0, zero findings, three NOT MEASURED in the gates' own words — check-test-completeness.mjs exit 3 (PREREQUISITE NOT MET, it grades a saved turbo run test log; the gate itself says this is not a red), check-half-states.mjs exit 3 (PREREQUISITE NOT MET, repo-scoped reads answer 403 in this session class), and check:type-check-debt exit 124 (killed at a 540 s bound while --re-measure re-ran tsc per ledger entry; CI's lint.yml measures it).

That union still stands at the patched head, and the reason is checkable: origin/main has not touched any of this PR's three files since the merge base, and the deriver emits the SAME 38 families from the SAME three paths — the command list is byte-identical (diff clean). What changed is content inside those paths, so the content-sensitive members were re-run at 0337430d4c: pnpm check:nul-bytes, check-empty-changeset, check-changeset-no-major, check-keyed-text-bounds, check-comment-mask-adoption, check:test-source-alias, check:cross-package-test-inputs — all EXIT=0.

One transient red is worth recording because it reads like a real finding: pnpm check:dual-build-cjs-loads once reported 17 @objectstack/spec "types NOT emitted though packages/spec/dist exists" findings — residue of a spec build this seat had killed mid-DTS while chasing the ratchet's prerequisite, a local dist state and not a source defect. After a full rebuild (check-dts-emitted: @objectstack/spec - 34/34 declared declaration file(s) present) the gate is exit 0, and that is the run recorded above. Nothing in this PR touches packages/spec.

Shared verify lock. Heavily contended across both rounds (repeated exit 99 queue timeouts, holders named in each VERDICT line). Locked runs: the dependency-closure builds, the typecheck and the pin. Declared narrowing, run unlocked: the ablations (single-file vitest runs over a source-reading test), the check:* gate union and pnpm lint — check:* gates and eslint are outside the lock's own stated coverage.

Boot measurement rig

The two readings were produced with throwaway scripts under this session's scratchpad, outside the repo — nothing in this PR is instrumentation. The examples/app-showcase run used the app unmodified; the content reading used a temp host config whose node_modules was symlinked to the showcase's so @objectstack/* resolved through the workspace.

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza